#ifndef SFT_SERVER_FILE_UTILS_H
#define SFT_SERVER_FILE_UTILS_H

#include "protocol.h" // For file_entry_t
#include <sqlite3.h>  // For sqlite3 type if needed by other utils in future, or for consistency

/**
 * @brief Lists files physically present in a user's upload directory.
 *
 * This function scans the user's designated upload directory on the server's file system
 * (e.g., /tmp/sfts_uploads/<user_id>/<requested_virtual_path>).
 * It populates an array of file_entry_t structures with details for each file found.
 * Directories within the user's space are currently skipped and not listed.
 *
 * @param user_id The ID of the user whose files are to be listed.
 * @param requested_virtual_path The virtual path requested by the client (e.g., "/").
 *                               This is appended to the user's base upload directory.
 *                               Care should be taken for path sanitization if subdirs are fully supported.
 * @param file_entries_list Pointer to a file_entry_t pointer. On success, this will be updated
 *                          to point to a dynamically allocated array of file entries.
 *                          The caller is responsible for freeing this memory.
 * @param count Pointer to an integer. On success, this will be updated with the number
 *              of file entries in the list.
 * @return 0 on success, -1 on critical error (e.g., malloc failure).
 *         If the directory doesn't exist or is empty, it returns 0 with *count = 0.
 */
int list_uploaded_files_for_user(sqlite3 *db, int user_id, const char *user_base_physical_dir, const char *requested_virtual_path, file_entry_t **file_entries_list, int *count);

// Potentially other file utility functions for the server can be added here later.
// For example, a function to safely construct and validate file paths on the server.

#endif // SFT_SERVER_FILE_UTILS_H